home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / demos / GL / buttonfly / menus / README < prev   
Encoding:
Text File  |  1994-08-02  |  7.7 KB  |  169 lines
  1.  
  2.      This directory contains menu files used by the buttonfly program.
  3.  
  4.      This example illustrate an easy-to-configure method of creating a
  5.      button heirarchy.
  6.  
  7.      Note that the ".menu" file in this directory is the top-level
  8.      menu for the first button encountered after starting up the demo.  
  9.      All the ".menu" files that live beneath this directory conform to
  10.      this methodology to produce nested levels of buttons.
  11.  
  12.      To run this example, the entire <toolbox>/src/demos and
  13.      <toolbox>/data subtrees must be available.
  14.  
  15.      What follow is a liberal extract from the buttonfly(6D) man page on
  16.      how to configure Buttonfly to better customize it to fit your needs.
  17.  
  18.  
  19. RECONFIGURING BUTTONFLY
  20.  
  21.      Buttonfly's menus were designed to be simple to change with any UNIX
  22.      text editor (such as vi ).  When it is run with no arguments, it looks
  23.      for button descriptions in a file called '.menu' in the current
  24.      directory.  If it is given one argument, it will look in that file
  25.      for button definitions instead.
  26.  
  27.      Buttonfly uses a very simple format to describe its buttons.  The
  28.      format has four different kinds of lines: comments, titles, actions,
  29.      and commands.
  30.  
  31.      Any line beginning with a '#' character is considered a comment and is
  32.      ignored.
  33.  
  34.      Button titles, like comments, always start in the first column of the
  35.      file, and may be anything not starting with a '#'.  Titles may be a
  36.      maximum of 36 characters long; buttonfly will automatically separate the
  37.      title into a maximum of three lines of twelve characters, separating
  38.      words in the title at spaces.
  39.  
  40.      Action lines start with a tab and end with a newline, and may be any
  41.      UNIX command.  Multiple actions may be specified for a button by listing
  42.      them after the button one per line, each starting with a tab.  Actions
  43.      may not span more than one line, but may be any length.  If no actions
  44.      are speci- fied for a button, the button is displayed, but nothing will
  45.      happen when it is selected.
  46.  
  47.      Commands, like actions, start with a tab character.  Currently, the
  48.      commands recognized are '.menu.', '.popup.', '.cd.', '.color.',
  49.      '.backcolor.', and '.highcolor.'.  Everything else is assumed to be an
  50.      action and will be executed as a UNIX command in a shell (see sh(1)).
  51.  
  52.      The special action called '.menu.' is used to specify a button that has
  53.      several buttons attached to the back of it.  When buttonfly sees '.menu.
  54.      filename' it will create a new set of buttons from the descriptions in
  55.      'filename'.  If it cannot find 'filename' in the current directory, then
  56.      nothing happens.  If 'filename' is '-', then the new set of buttons is
  57.      created from the standard output of the previous actions (see example
  58.      below).  Note that any 'cd' commands in an action list do not affect the
  59.      directory in which buttonfly looks for the filenames specified in
  60.      '.menu.' commands, becuase actions are executed in a sub-shell (see the
  61.      '.cd.' command below).
  62.  
  63.      Another special actions is '.popup.'.  It is used to define a pop-up
  64.      menu entry attached to a button.  When buttonfly sees '.popop. title'
  65.      it adds an entry 'title' to the button's pop-up menu.  The actions
  66.      following a .popup. command will be executed when that menu entry is
  67.      chosen.  Buttonfly automatically provides a 'Do It' entry, which has
  68.      the same effect as pressing the left mouse button.
  69.  
  70.      The '.cd.' action is used to change buttonfly's idea of the current
  71.      working directory.  When the button containing the .cd. command is
  72.      pressed, buttonfly will chdir into that directory before executing
  73.      that button's actions, and all buttons underneath that button will
  74.      also be executed in that directory (unless they also have .cd. commands).
  75.      Note that executing the regular 'cd' shell command in a button does not
  76.      affect buttonfly's idea of the current working directory, since all
  77.      button actions are executed in their own shell environment.
  78.  
  79.      The command '.color.' followed by three numbers in the range 0.0 ... 1.0
  80.      specifies the red, green and blue components of a button's color, and
  81.      '.highcolor' does the same for the color of the button as it is being
  82.      selected.  '.backcolor.' changes the color of the back of the button,
  83.      which becomes the background color of the next set of buttons (displayed
  84.      when the button flips over).  Note that using color commands at the top
  85.      of a file, before any buttons have been defined, causes the default
  86.      colors to be changed for all subsequent buttons.  To change the
  87.      background color to red for the first button and all subsequent
  88.      buttons you would specify:
  89.  
  90.           .backcolor. 1.0 0.0 0.0
  91.  
  92.      in the menu description file before any buttons are defined.
  93.  
  94. EXAMPLES
  95.  
  96.      The following are example buttonfly .menu files, with descriptions of
  97.      what they do.
  98.  
  99.      This is a very simple button called 'First' that has the buttons defined
  100.      in the file '.menu_second' on the back of it.
  101.  
  102.           First
  103.                .menu. .menu_second
  104.  
  105.      Here are three buttons.  The 'Parent' button is purple and will flip
  106.      over and display the other two buttons when pressed (they will be
  107.      displayed on a purple background, since that is the color on the back
  108.      of the first button).  The 'Demonstrate...' button changes directories
  109.      and then runs a program when pressed, and 'Recurse' flips over and shows
  110.      the first button again, this time on a blue background since the
  111.      '.backcolor.' command changes the background color to blue.
  112.  
  113.           #Save this in a file called '.menu'
  114.           Parent
  115.                .color. .89 .10 .89
  116.                .backcolor. .89 .10 .89
  117.                .highcolor. 1.0 .5 1.0
  118.                .menu. child
  119.  
  120.           #Save the following buttons in a file called 'child'
  121.           Demonstrate GL/NeWS Interface
  122.                cd /usr/NeWS/demo
  123.                glnews
  124.           Recurse
  125.                .backcolor. 0.0 0.0 1.0
  126.                .menu. .menu
  127.  
  128.      Here is a very complicated button, which builds a button file based
  129.      on the files it finds in a directory full of files.  When pressed,
  130.      it builds the file and then uses .menu.  to flip over, exposing entries
  131.      for all the files it found.  Note that this allows you to delete or add
  132.      image files, and the buttons will always be accurate.  It also has a
  133.      pop-up menu on it giving help; the first .popup command specifies the
  134.      title of the menu using the %t feature of Silicon Graphics menus.
  135.  
  136.           Show An Image
  137.                cd /usr/demos/data/images
  138.           #The following two lines must all be on the
  139.           # same line in the .menu file
  140.                /bin/ls *.rgb | awk 'BEGIN{FS="."}{print "Show " $1
  141.           "\n\tipaste /usr/demos/data/images/" $0 "\n"}'
  142.                .menu. -
  143.                .popup. ShowImage Menu %t
  144.                .popup. Ipaste Man Page
  145.                wsh -c man ipaste
  146.  
  147. BUGS
  148.  
  149.      Buttonfly will not work if the first character of a file is a TAB
  150.      followed by anything other than .color., .backcolor., or .highcolor.
  151.      It is safest to eliminate any blank lines from the files you create.
  152.  
  153.      Buttonfly may crash if given an arbitrary file as input.
  154.  
  155.      The maximum number of buttons on any level of the hierarchy is 32.
  156.  
  157.      If a program fails to run, nothing happens-- no error messages or
  158.      warnings are given.  This can be considered either a feature or a bug.
  159.  
  160.      Specifying %F, %f, %x, or %m as part of a .popup. title will give bad
  161.      results, and may crash the program.  Using %t to specify a title works,
  162.      but any actions specified for that entry will never be executed (since
  163.      it is impossible to select a title entry).
  164.  
  165. FILES
  166.  
  167.      /usr/demos/.m* are the button files the demos use.
  168.  
  169.